PC Electronic Plus

home *** CD-ROM | disk | FTP | other *** search

/ PC Electronic Plus / PC Electronics Plus (Most Significant Bits)(1995).ISO / pcreson / resonpc.doc < prev next >

Wrap

Text File | 1995-01-17 | 67KB | 1,901 lines

PC-RESON version 1.00 Command and Element Reference February 1992 By John A. Priller and John Vincent Edited by Becky Palmer-Scott National Superconducting Cyclotron Laboratory Michigan State University East Lansing, MI 48824-1321 TABLE OF CONTENTS COPYRIGHT INFORMATION & PROGRAM DESCRIPTION..................... 1 REQUIRED SOFTWARE & HARDWARE ................................... 2 RUNNING RESON .................................................. 3 CONVENTIONS & TIPS ON USING RESON FOR AC ANALYSIS .............. 4 Nomenclature: Elements, Terminals, and Nodes ................. 4 Circuit Nodes ................................................ 4 Voltage Loops ................................................ 4 Linear AC Analysis ........................................... 5 Current Flow ................................................. 5 Output Dimensions ............................................ 5 Tips ......................................................... 5 INPUT FILE FORMAT .............................................. 6 Text Format .................................................. 6 Upper and lower case ....................................... 6 Numeric fields ............................................. 6 Text strings ............................................... 7 Line Format .................................................. 7 Comment format ............................................. 7 Command format ............................................. 7 Element statement format ................................... 7 Sample Input Files ........................................... 8 OUTPUT FUNCTIONS ............................................... 9 V -- Voltage ................................................. 9 VD -- Device Voltage ......................................... 9 I -- Current ................................................ 10 ID -- Device Current ........................................ 10 IS -- Source Current ........................................ 10 IN -- Node Current .......................................... 10 P -- Power .................................................. 11 U -- Energy ................................................. 11 Q -- Quality Factor ......................................... 11 N -- Node Number at Given Terminal .......................... 11 RESON COMMANDS ................................................ 12 Define Data Parameters ...................................... 12 .MAT ...................................................... 12 .UNIT ..................................................... 12 .VSCALE ................................................... 12 Invoke Circuit Analysis ..................................... 13 .AC ....................................................... 13 .REPORT ................................................... 13 .INCLUDE .................................................. 13 Specify Output Appearance................................... 14 .COLUMNS .................................................. 14 .MARGIN ................................................... 14 .PRECISION ................................................ 14 .TITLE .................................................... 14 Specify and Generate Output Topics .......................... 15 .PRINT ................................................... 15 .OUTPUT ................................................... 16 .COUPLE ................................................... 17 .SHUNT .................................................... 17 (Continued on next page) TABLE OF CONTENTS (cont.) RESON ELEMENT STATEMENTS: GENERAL FORMAT ...................... 18 NAME ........................................................ 18 Terminal Connections ........................................ 18 Required Parameters ......................................... 18 Optional Parameters ......................................... 18 RESON ELEMENT STATEMENTS: INDIVIDUAL FORMATS .................. 19 Components .................................................. 19 C -- Capacitor ............................................ 19 K -- Coupled coil ......................................... 19 L -- Inductor ............................................. 19 R -- Resistor ............................................. 19 Transmission lines ........................................ 20 T -- General transmission line .......................... 20 TC -- Coaxial transmission line ......................... 20 TR -- Rectangular (plate) transmission line ............. 20 Voltage Sources ............................................. 22 V -- Independent voltage source ........................... 22 H -- Current-controlled voltage source .................... 22 E -- Voltage-controlled voltage source .................... 22 Current Sources ............................................. 23 I -- Independent current source ........................... 23 F -- Current-controlled voltage source .................... 23 G -- Voltage-controlled voltage source .................... 23 ERROR MESSAGES ................................................ 24 RESON Errors ................................................ 24 Compiler Errors ............................................. 25 DOS errors ............................................... 25 I/O errors ............................................... 27 Critical errors .......................................... 28 Fatal errors ............................................. 28 - 1 - COPYRIGHT INFORMATION The copyright ((c) 1991, 1992) on this software product is held by John Vincent, John A. Priller, and Michigan State University. All rights are reserved. The above individuals and institutions reserve the right to limit distribution of this software, within the bylaws of Michigan State University, and within the copyright laws of the State of Michigan and of the United States of America. The authors of this software have used their best efforts in preparing it. These efforts include development, research and testing of the theories and algorithms to determine their correctness and effectiveness. The authors of this software and Michigan State University make no warranty of any kind, expressed or implied, with regard to this software or to its documentation. The authors of this software and Michigan State University shall not be liable in any event for incidental or consequential damages in connection with, or rising out of, the furnishing, performance, use or misuse of this software. PROGRAM DESCRIPTION RESON is a enhanced AC circuit-analysis program modeled loosely on SPICE. "Enhanced" means that beyond solving for voltages and currents, RESON computes circulating and dissipated energy, and allows for material properties and geometry. RESON also has additional output functions and formats. All of RESON's input and output files are standard ASCII, and can be created and read by most computer systems. Input files look similar to SPICE input files. Input files contain statements and comments which describe the circuit and the analysis to be performed. (Since the program currently does AC analysis only, SPICE-like statements for DC or transient analysis are not included). Output files have quote-delimited strings and comma- delimited numeric fields, so that they may be easily imported into spreadsheet programs (such as Lotus 123, or Borland's Quattro). All user I/O and data management is performed by routines written by John Priller, while the computation and analysis engine was written by John Vincent. Please direct questions pertaining to RESON to the appropriate individual. - 2 - REQUIRED SOFTWARE RESON is shipped with the following files: RESON.EXE -- The RESON program RESON.DOC -- This document MATERIAL.RSN -- The materials data file UNITS.RSN -- The units data file README.DOC -- Last-minute notes and information *.DAT-- Sample input files RESON requires the MS-DOS or PC-DOS version 2.1 (or higher) operating system to run. It may also be possible to run RESON from a Microsoft Windows 3.0 or OS/2 "DOS window", though this has not yet been verified. REQUIRED HARDWARE RESON requires the following minimum hardware setup: - An IBM-compatible PC with an Intel 8088 or higher CPU; an 80386 or i486 is preferred. - A math coprocessor chip, such as an 80387 (the i486 chip includes a math coprocessor) is recommended but not necessary. - 640K of RAM - A hard disk is recommended but not necessary. - 3 - RUNNING RESON RESON reads an input file (e.g. RFSTUFF.DAT) and creates an *.OUT file (e.g. RFSTUFF.OUT) and any other output files requested in the input file (e.g. RFSTUFF.0...RFSTUFF.n). If errors are encountered, error log RFSTUFF.LOG is created instead of the output files. RESON files consist of command statements and element statements (described in this manual), and any desired comment statements. To run RESON, type RESON filename.ext ; RESON accepts any filename or RESON filename ; ".DAT" is assumed if no extender is given or RESON filename.ext > nul ; "nul" prevents program status from RESON filename > nul appearing on screen during the run. With each new RESON run, new output files are created -- RESON will not append data from a new run onto an old output file. Old output files with identical names will be destroyed. However, during the same run, data can be appended to an existing output table -- see the .PRINT, .OUTPUT, .COUPLE, and .SHUNT commands in the section, "Specify and Generate Output Topics." - 4 - CONVENTIONS AND TIPS ON USING RESON FOR AC ANALYSIS Nomenclature: Elements, Terminals, and Nodes In RESON, "elements" are components or power sources, which have "terminals" connecting them to a circuit. "Nodes" are the circuit locations the terminals connect to. In most statements, you replace each terminal designator with the number of its circuit node. Terminals are numbered left to right, so in this resistor definition, RSHUNT 15 4 100k terminal 1 connects to node 15, and terminal 2 to node 4. However, terminal numbers are used explicitly in some .OUTPUT and .PRINT functions. For the resistor defined above, the following commands request the same voltage sets: .PRINT AC V(15) V(4) ; Voltages at terminal 1 and terminal 2 requested = with corresponding nodes .PRINT AC VD(RSHUNT,1) VD(RSHUNT,2) ; Voltages at terminal 1 and terminal 2 requested with terminal numbers Circuit Nodes Node numbers are always positive integers. They do not have to be used sequentially -- node numbers may be skipped if desired. Node 0 is reserved for ground. The circuit must have connections to this node. Each node (including ground) must have at least two connections. RESON will check the circuit for this requirement before attempting to process it. Nodes do not require a DC path to ground. Voltage Loops Loops of voltage are illegal. RESON does not currently check for this condition, so the user must take care that it does not occur. - 5 - Linear AC Analysis RESON's AC analysis solves for the small-signal frequency response. All non-linear elements are made linear about the operating point by user input model parameters or by idealized default parameters. For example, if the model parameters specify a gain of ten, then the gain remains ten no matter what the input level. An input of 1 would result in an output of 10, an input of 10 results in 100, etc. The gain has become linear. Current Direction 1) Positive current flows in the direction positive charges would go. 2) Positive current flows into component terminals. 3) Positive current flows through sources from the positive to the negative terminal. Output Dimensions All output dimensions are in meters, regardless of input units. See also Tips below. Tips -- To get average power and energy values from the output functions, enter all source values in RMS units. To get peak power and energy values, enter all source values in peak units. -- In most RESON statements, you need to replace the terminal number with the corresponding circuit node. -- RESON sweeps the frequency of the source(s) to determine the circuit's response. If your circuit has only one AC input, you can set the AC input equal to 1 with a phase angle of 0; the output at any node will then conveniently reflect the transfer function. -- If you have a single input source set to 1 volt or 1 amp, you can scale the resulting computed energies for some new source value 'V' or 'I' by multiplying all energies by V*V or I*I. (Also see .VSCALE command.) - 6 - INPUT FILE FORMAT The circuit that RESON will analyze is described by a netlist. This is a group of statements, each of which identifies a circuit element, its interconnecting nodes, and its properties. In addition to the netlist, a RESON input file also contains commands that direct the analyses to be performed and the output to be created. An input file may also include comment lines, which describe the circuit and analyses for future reference. All of these are described individually below. Text Format Upper and lower case With the exception of 'm' and 'M' metric suffixes for numeric fields, RESON is not case-sensitive; that is, RTOP = Rtop = rTop Numeric fields Numeric fields in RESON can be either integer, floating point 'F' or floating point 'E' format: Integer : 0 7 91 8M 'F' floating point : 17.1m 35.88k 1641.002 'E' floating point : 1E-8 4.02E+6 As shown above, metric suffixes are supported for all real- number fields (everything except terminal and node numbers). The suffixes RESON recognizes are: a,A (atto) = 1.0E-15 k,K (kilo) = 1.0E+03 p,P (pico) = 1.0E-12 M (mega) = 1.0E+06 n,N (nano) = 1.0E-09 g,G (giga) = 1.0E+09 u,U (micro) = 1.0E-06 t,T (tera) = 1.0E+12 m (milli) = 1.0E-03 No spaces or other characters may occur between the final character of the number and the suffix, and any characters beyond the initial suffix character are ignored. All formats below are acceptable for denoting 4 megahertz (or 4 meg of anything): 4000000.0 * Straight 'F' floating point with no suffix 4.0E+6 * 'E' floating point 4.0M * 'F' floating point with 'M' (mega) suffix 4Mhz * Integer with 'M' suffix -- the 'hz' is ignored Note also that for milli- and mega-, the uppercase and lowercase letter 'm' is distinct. - 7 - Text strings Text strings can be at most 64 characters; element names are limited to 10 characters. Strings enclosed within quotes may contain any characters. Those not within quotes: - Cannot begin with a number - May include percent (%) - Cannot contain spaces - May include ampersand (&) - May include dollar sign ($) - May include underscore (_) Examples: A_STRING "This is another string" 'So is this' Line Format Input file syntax is free-format, with fields separated by one or more blanks, tabs, commas or parentheses. Carriage returns mark the end of each input line. Blank lines are ignored. Each RESON element or command must be defined on a single line, although a line continuation character, the vertical bar (|), can be placed at the end of a line to denote that the following line is a continuation of the previous one: * This comment looks like | a single line to RESON! Comment format Comments begin with an asterisk (*) or a semi-colon (;), and are ignored during input file processing. Comments may occur at the end of command and element lines. Command format RESON command lines begin a period, just as SPICE commands do. In the following descriptions, items in angle brackets (<>) are mandatory, those within square brackets ([]) are optional, and options separated by vertical bars (|) mean that one and only one of the set may be chosen. (Do not include brackets in actual RESON statements.) Example: .REPORT <AC | DC> <frequency> [TITLE=string] In this .REPORT command, AC or DC must be chosen; the frequency must be given; there needn't be a title string. Element statement format No characters precede the element statement. See the RESON ELEMENT STATEMENT sections for details on statement format. - 8 - Sample Input Files These files can be found on the RESON program disk. QWAVE2.DAT Notice that element statements beginning "ISRC," "T1" and "TR1" are disabled by the comment * preceding them. ; ; A quarter-wave resonator ; ; This example is from "Engineering Electromagnetics" by ; William H. Hayt, Fourth edition. pp 474 - 477. ; TC1 is the line described by Hayt while the rest of the ; lines are equivalent to TC1 using the available RESON ; models. Only one line per run should be uncommented. ; ; RLC.DAT is the equivalent shunt circuit of this resonator ; ; coupling has been added .MAT SILVER .Columns 6 .UNIT Centimeter *ISRC 1 0 53.2uA 0 V1 999 0 61.912mV 0.0 Cc 999 1 1.368pF TC1 1 2 0 Ri=1 Ro=2.72 L=37.5 E=4 QE=1000 *T1 1 2 0 Z0=30.0 TD=2.5nS E=4 QE=1000 RABAC=4.026uOhms RCOMAC=1.48uOhms *TR1 1 2 0 Z0=30.0 Wa=6.2832 Wc=17.0903 L=37.5 E=4 QE=1000 *TR1 1 2 0 H=1.86 Wa=6.2832 Wc=17.0903 L=37.5 E=4 QE=1000 R1 1 0 100Mohm VShort 2 0 0.0 0.0 .AC LIN 25 98.310Mhz 98.560Mhz .PRINT AC V(1) I(VShort) .Report AC 98.378940Mhz .Output 1 "" ALL $ VDm(1) IDm(1) Pc Pe Ue Uh *.Couple 1 "Test Capacitive Couple" Node=1 Z0=50 *.Couple 1 "Test Tline Couple" Tname=TC1 Z0=50 ; ; RLC.DAT ; ; A RLC equivalent shunt circuit model of QWAVE2.DAT ; .Columns 6 V1 999 0 62.890mV 0.0 Cc 999 1 1.368pF L1 1 0 60.74nH C1 1 0 41.64pF R1 1 0 26.56kOhms .AC LIN 25 98.310Mhz 98.560Mhz .PRINT AC V(1) I(VShort) .Report AC 98.4700Mhz .Output 1 "" ALL $ VDm(1) IDm(1) Pc Pe Ue Uh - 9 - OUTPUT FUNCTIONS Output functions, used in the .OUTPUT and .PRINT commands, compute or return results based on RESON analysis. They begin with an identifier, such as "V" or "P," which specifies the type of information desired, and which is sometimes followed by an operator: "i," "r," "m," or "p" to describe a complex number component or "c," "e," or "h" to describe the type of power or energy. Most functions also list the circuit nodes, element names, and/or terminals the information is about. Element names are always omitted in .OUTPUT function statements. This section describes the functions available. In the following descriptions, items in angle brackets (<>) are mandatory, those within square brackets ([]) are optional, and options separated by vertical bars (|) mean that one and only one of the set may be chosen. In addition, items in {} brackets must be in .PRINT commands but should not be in .OUTPUT commands. Include parentheses but not brackets in actual RESON statements. V -- Voltage (volt): Determines the potential difference between two nodes, where V = V(nodeX) - V(nodeY). V[i|r|m|p](nodeX[,nodeY]) i = imaginary part Example: VM(11) for .PRINT r = real part m = magnitude p = phase nodeX = a node number nodeY = another node number; if not entered, node 0 is assumed VD -- Device Voltage (volt): Determines the potential difference between the element terminals or between an element terminal and ground, where VD = VD(terminalX) - VD(terminalY). VD[i|r|m|p]({element,}terminalX[,terminalY]) i = imaginary part Examples: VD(1,2) for .OUTPUT r = real part VD(1) for .OUTPUT m = magnitude VD(C16,1,2) for .PRINT p = phase VD(C16,1) for .PRINT element = element name terminalX = a terminal number terminalY = another terminal number; if not entered, the potential difference between terminalX and node 0 is assumed. - 10 - I -- Current (ampere): Determines the current through a voltage source. I[i|r|m|p](vname) i = imaginary part Example: IM(V1) for .PRINT r = real part m = magnitude p = phase vname = voltage source name ID -- Device Current (ampere): Determines the current entering a device terminal. ID[i|r|m|p]({element,}terminal) i = imaginary part Examples: ID(1) for .OUTPUT r = real part ID(C8,1) for .PRINT m = magnitude p = phase element = element name terminal = terminal # IS -- Source Current (ampere): Determines all current from current source(s) attached to the node. IS[i|r|m|p](node) i = imaginary part Example: IS(11) for .PRINT r = real part m = magnitude p = phase node = node number IN -- Node Current (ampere): Determines the total current crossing a node. (Currently doesn't work properly.) IN[i|r|m|p](node) i = imaginary part Example: IN(4) for .PRINT r = real part m = magnitude p = phase node = node number - 11 - P -- Power (watt): Determines the energy dissipated due to conduction currents, electric energy, magnetic energy, or the energy delivered by any source. Power delivered is negative; power dissipated is positive. If no subscript modifier is given, the total power (Pc + Pe + Ph) is reported. P[c|e|h]{(element)} c = conductive losses Examples: P for .OUTPUT e = electric P(R17) for .PRINT h = magnetic PH(R44) for .PRINT element = element name U -- Energy (VAR): Determines the magnetic or electric reactive energy. If no subscript modifier is given, the total energy (Ue + Uh) is reported. U[e|h]{(element)} e = electric Examples: U for .OUTPUT h = magnetic Ue for .OUTPUT element = element name Uh(LTOP) for .PRINT Q -- Quality Factor: Determines the quality factor Q, which equals energy/power; (Q = U/P). Q{(element)} element = element name Examples: Q for .OUTPUT Q(CAP1) for .PRINT N -- Node Number at Given Terminal: Determines the node number to which the specified terminal is connected. N({element,}terminal) element = element name Examples: N(1) for .OUTPUT terminal = terminal # N(CAP1,1) for .PRINT - 12 - RESON COMMANDS In the following descriptions, items in angle brackets (<>) are mandatory, those within square brackets ([]) are optional, and options separated by vertical bars (|) mean that one and only one of the set may be chosen. (Do not include brackets in actual RESON statements.) Define Data Parameters The following commands provide default values for the input file. See RESON ELEMENT STATEMENTS for individualized parameter definitions. .MAT <material> Defines the material that RESON should use in calculating default properties for subsequent elements. Supported materials are listed in the MATERIAL.RSN data file, and the first material in this file (usually COPPER) is the default material if none is specified. Additional materials may be added to the MATERIAL.RSN file by the user. Multiple .MAT commands may be used to define parts of the circuit which are made of differing materials. Example: .MAT SILVER .UNIT <unit_name> Defines the units that RESON should use in size specifications and in calculating default properties for subsequent elements. Supported units are listed in the UNITS.RSN file, and the first unit in this file (usually the METER) is the default unit if none is specified. Additional units may be added to the UNITS.RSN file by the user. Multiple .UNIT commands can be used to define different parts of the circuit. Example: .UNIT INCH .VSCALE <node> <value> Scales the matrix solution so that the voltage at the given node is the given value. Only one .VSCALE command is allowed per case. Example: .VSCALE 17 100 - 13 - Invoke Circuit Analysis .AC LIN <NumIntervals> <Start-Freq> <End-Freq> Performs an AC analysis of the circuit defined by the input file, over the region of frequencies specified. LIN indicates a linear division of the frequency range. Example: .AC LIN 10 8.9MHz 9.1MHz .REPORT AC <frequency> [TITLE=string] Performs a circuit analysis. Multiple .REPORT commands in an input file will be processed in the order encountered. Example: .REPORT AC 1.0MHz TITLE="Test circuit at 1Mhz" .INCLUDE <filename> Processes the specified input file for RESON commands and elements. Any number of nested .INCLUDE files may be specified (.INCLUDEd files may .INCLUDE other files). Example: .INCLUDE "SUBCIRC.DAT" - 14 - Specify Output Appearance .COLUMNS <number> Specifies the maximum number of data columns for .PRINT, .OUTPUT, .COUPLE, and .SHUNT commands. Default is 5. Only one .COLUMNS command per input file will be obeyed; if more than one is encountered, the last one will be used. Example: .COLUMNS 8 .MARGIN <number> Defines left margin of RESON output. Default is 6 spaces. Example: .MARGIN 12 .PRECISION <freq-precision> <other-precision> Specifies the number of significant digits to use in floating-point output. "freq-precision" specifies the number of significant digits for frequency output; "other- precision" specifies the number of significant digits for all other floating-point output. Only one .PRECISION command per input file will be obeyed; the last one will be used. The default for .PRECISION is 6, 4. The width of a floating point data column is: column width = 6 + significant digits + comma + space = significant digits + 8 6 significant digits = +0.00000E+00 ; width = 14 4 significant digits = +0.000E+00 ; width = 12 Commas are added to the output to insure compatibility with spreadsheet import formats. Example: .PRECISION 8 6 .TITLE <string> Specifies the title for the RESON case. "string" is a text string and must be within quotes if more than one word. Example: .TITLE "Test Resonator" - 15 - Specify and Generate Output Topics .PRINT AC <function-list> Writes data from the previous .AC analysis command to a filename.OUT file. ("filename" is the same as the input "filename".) Multiple .PRINT commands can exist in an input file; the data will be appended to filename.OUT. Function lists consist of one or more functions from the following table: Function Description Example ------------------------------------------------------------ P[c|e|h](element) ; Power P(R44) U[e|h] ; Energy Ue(CAP1) Q(element) ; Quality factor Q(CAP1) N(element,terminal) ; Node # at terminal N(CAP1,1) V[r|i|m|p](node1[,node2]) ; Voltage VM(11) I[r|i|m|p](vname) ; Current IM(V1) IN[r|i|m|p](node) ; Node current IN(4) IS[r|i|m|p](node) ; Source current IS(11) VD[r|i|m|p](element, ; Device voltage VD(C16,1,2) terminalX[,terminalY]) ID[r|i|m|p](element, ; Device current ID(C8,1) terminal) ------------------------------------------------------------ where and P = Power c = conductive losses U = Energy e = electrical energy Q = Quality factor h = magnetic energy N = Node # at given terminal r = real part V = Voltage i = imaginary part IN = Node current m = magnitude IS = Source current p = phase VD = Device voltage ID = Device current Examples: .PRINT AC V(15) V(4) .PRINT AC VD(RSHUNT,1) VD(RSHUNT,2) .PRINT AC ISR(11) VM(11) I(12) V(12) - 16 - .OUTPUT <output-file#> <title> <element-list> $ <function-list> Generates a table from a previous .REPORT analysis, with functions in the columns and elements in the rows. Multiple .OUTPUT commands may exist for each .REPORT . .OUTPUT command format is below. Note the required '$' between the element list and function list. Also, the number of functions requested must be less than the number of columns requested by the .COLUMNS command. output-file# : The numeric extender of the output file: filename.0 to filename.9. ("filename" is automatically the same as the input "filename".) With each new RESON run, a brand new output file is opened, if requested. If .OUTPUT commands repeat the file extender during the RESON run, the data will be appended to the output file. title : Text-string title for the output. element-list : The elements to include in the output rows. Elements may be specified individually, in groups, or in a combination of the two: Examples: TR17 : Rectangular transmission line TR17 TR : All rectangular transmission lines C : All capacitors C1-R12: Input file elements from C1 to R12, in order ALL : All elements in input file order function-list : The data to be displayed in the output columns. Includes any of the following: VD[i|r|m|p](tx[,ty]) : Device Voltage ID[i|r|m|p](t) : Device Current Q : "Q" quality factor P[c|e|h] : Power (W) ; If no subscripts, U[e|h] : Energy (VA) ; total is given. where and P = Power c = conductive losses U = Energy e = electrical energy Q = Quality factor h = magnetic energy VD = Device voltage r = real part ID = Device current i = imaginary part m = magnitude p = phase Examples: .OUTPUT 1 "Parallel resonator Response" R L C $ Ue P .OUTPUT 0 "" TR R1-C11 $ VD(1,2) ID(1) - 17 - .COUPLE <output-file#> <title> <node=# | Tname=xxx> <Z0=R> Generates data from the last .REPORT analysis. Multiple .COUPLE commands may exist for each analysis. Matches a feed transmission line of characteristic impedance "Z0" to the circuit. If "node=#" is requested, reports the series capacitance and frequency shift needed at that node. If "Tname" is requested, reports the distance from terminal t2 of "Tname" transmission line where the feed transmission line can be tied directly. The result is valid only if the circuit is resonant. output-file# : The numeric extender of the output file: filename.0 to filename.9. ("filename" is automatically the same as the input "filename".) With each new RESON run, a brand new output file is opened, if requested. If .OUTPUT commands repeat the file extender during the run, the data will be appended to the output file. title : Text-string title for the output. node=# : The statement "node=#" where "#" is the node number of the circuit to couple to. Tname : The statement "Tname=xxx" where "xxx" is the name of the transmission line to couple to. Z0=R : The statement "Z0=R", where "R" is the characteristic impedance (in ohms) of the feed line to match to the circuit. Examples: .COUPLE 1 "Capacitive Coupler" node=6 Z0=50 .COUPLE 0 "Direct Feed" Tname=T11 Z0=50 .SHUNT <output-file#> <title> <node#> Generates data from the last .REPORT analysis. Multiple .SHUNT commands may exist for each analysis. Determines the equivalent shunt circuit at the specified circuit node. The result is only valid if the circuit is resonant. output-file# : The numeric extender of the output file: filename.0 to filename.9. ("filename" is automatically the same as the input "filename".) With each new RESON run, a brand new output file is opened, if requested. If .OUTPUT commands repeat the file extender during the run, the data will be appended to the output file. title : Text-string title for the output. node# : The node number at which to determine the equivalent shunt circuit. Example: .SHUNT 0 "Shunt circuit at node 10" 10 - 18 - RESON ELEMENT STATEMENTS: GENERAL FORMAT Element statements define the circuit that RESON will analyze. Statement structures vary, but have several parts in common: NAME <t1>..<tn> <required_parameter=#>..[optional_parameter=#]... NAME An element NAME can be up to 10 characters long. The first character (and second character, in the case of transmission lines) determines what type of element is being defined. The rest of the name is determined by the user. Element names in a circuit must be unique! First characters of names are: C... : capacitor K... : coupled coil L... : inductor R... : resistor V... : independent voltage source H... : current-controlled voltage source E... : voltage-controlled voltage source I... : independent current source F... : current-control current source G... : voltage-control current source T... : general transmission line TC... : coaxial transmission line TR... : rectangular transmission line Terminal Connections t1..tn specify the terminal connections of the element. To insert an element into a circuit, you simply replace each terminal designator with the number of the circuit node it connects to. Terminals are numbered left to right, so in this resistor definition: RSHUNT 15 4 100k terminal 1 connects to node 15, and terminal 2 to node 4. Required Parameters Most required parameters will be a single number, but some take the form of XX=value, where XX is a one-or-more character identifier string, followed by an optional =, followed by a value (almost always a number). Optional Parameters Optional parameters always have the XX=value form. They must appear AFTER the required element parameters, but may appear in any order among themselves. - 19 - RESON ELEMENT STATEMENTS: INDIVIDUAL FORMATS Components RESON follows the standard engineering convention that positive current flows in the direction that positive charges would go, and flows into component terminals. C -- Capacitor: C... <t1> <t2> <value> [Q=value] Specifies a capacitor, with value specified in farads. If no Q is specified, it is assumed to be infinite. Replace t1 and t2 with the circuit nodes they connect to. K -- Coupled coil: K... <L1> <L2> <value> Couples two inductors, L1 and L2. Value is the coupling coefficient, and must be between 0 and 1. Establishes a mutual inductance, M, between L1 and L2, where M = value*SQRT(L1*L2). L -- Inductor: L... <t1> <t2> <value> [Q=value] Specifies an inductor, with value given in henries. The default Q value is infinite, if none is specified. Replace t1 and t2 with the circuit nodes they connect to. R -- Resistor: R... <t1> <t2> <value> Specifies a resistor. Value is in ohms. Replace t1 and t2 with the circuit nodes they connect to. - 20 - Transmission lines: A transmission line consists of two conductors of equal length. t1 and t2 are the terminal connections to the primary conductor, while both ends of the return conductor are tied to terminal t3. The voltage on the primary conductor varies according to the "unsimplified" lossy transmission line equations, while the voltage on the return conductor is held constant to the node voltage where t3 is tied. The current on the return conductor mirrors the current on the primary conductor. All length/width/height/radius parameters are assumed to be given in the currently selected units defined by the .UNIT command. All resistances are calculated using the default material parameters defined by the .MAT command. Si, So, Sa and Sc override these conductivity parameters. All dimensions are output in meters, regardless of input. General transmission line: T... <t1> <t2> <t3> <Z0=value> <TD=value> <RABDC=value> <RABAC=value> [RCOMDC=value] [RCOMAC=value] [E=value] [M=value] [QE=value] [QM=value] Coaxial transmission line: TC... <t1> <t2> <t3> <Ri=value> <Ro=value> <L=value> [Si=value] [So=value] [E=value] [M=value] [QE=value] [QM=value] Conductor resistance default values are computed from the conductor materials defined by the .MAT command. Si= and So= parameters will override these defaults. Rectangular (plate) transmission line: TR... <t1> <t2> <t3> <Wa=value> <Wc=value> <L=value> [Z0=value | H=value] [Sa=value] [Sc=value] [E=value] [M=value] [QE=value] [QM=value] If height (H) is specified, Z0 is computed assuming the width of each conductor is the average of Wa and Wc. If Z0 is specified, Wa and Wc are simply used for power calculations and height is irrelevant. At all times the current density of the primary and return conductors is assumed to be uniform. See parameter definitions on next page. - 21 - t1 : Terminal 1; replace with corresponding circuit node. t2 : Terminal 2; replace with corresponding node. t3 : Terminal 3; replace with corresponding node. E=n : Relative permittivity of media between conductors. Default = 1.0. M=n : Relative permeability of media between conductors. Default = 1.0. QE=n : Electric material quality factor (1/loss_tangent) computed from electric energy and losses (a measure of fill material losses due to electric fields). Default = infinity. QM=n : Magnetic material quality factor (1/loss_tangent) computed from magnetic energy and losses (a measure of fill material losses due to magnetic fields). Default = infinity. Z0=n : Characteristic impedance in ohms. Td=n : Time delay from t1 to t2, in seconds. RABDC=n : DC resistance per meter of conductor spanning t1 to t2. Default = 0.0. RABAC=n : AC resistance per meter per sqrt(Hz) of conductor spanning t1 to t2. Default = 0.0. RCOMDC=n : DC resistance per meter of return conductor. Default = 0.0. RCOMAC=n : AC resistance per meter per sqrt(Hz) of return conductor. Default = 0.0 Ri=n : Radius of inner conductor in current units. Ro=n : Radius of outer conductor in current units. Sa=n : Conductivity of primary conductor (mhos/meter). Sc=n : Conductivity of return conductor (mhos/meter). Si=n : Conductivity of inner conductor (mhos/meter). So=n : Conductivity of outer conductor (mhos/meter). Wa=n : Width of primary conductor in current units. Wc=n : Width of return conductor in current units. L=n : Length of both conductors in current units. H=n : Height between conductors in current units. - 22 - Voltage Sources For sources, RESON presumes that current flows from t1 (positive terminal) to t2 (negative terminal). Replace t1 and t2 with the circuit nodes they connect to. V -- Independent voltage source: V... <t1> <t2> <magnitude> <phase> Specifies an independent voltage source, with positive current flowing from terminals t1 to t2. Magnitude is specified in volts, phase in degrees. H -- Current-controlled voltage source: H... <t1> <t2> <Vname> <transresistance> Specifies a current-controlled voltage source between terminals t1 and t2. Vname is any independent voltage source defined elsewhere in the circuit. The voltage source has the value of I(Vname)*transresistance. E -- Voltage-controlled voltage source: E... <t1> <t2> <NC1> <NC2> <gain> Specifies a voltage-controlled voltage source between terminals t1 and t2. NC1 and NC2 are the positive and negative controlling nodes, respectively. The voltage source has the value of (V(NC1)-V(NC2))*gain. - 23 - Current Sources For sources, RESON presumes that current flows from positive to negative nodes. Replace t1 and t2 with the circuit nodes they connect to. I -- Independent current source: I... <t1> <t2> <magnitude> <phase> Specifies an independent current source, where t1 and t2 are the positive and negative terminals, respectively. Current is assumed to flow from t1 through the source to t2. Magnitude is specified in amps, phase in degrees. F -- Current-controlled current source: F... <t1> <t2> <Vname> <gain> Specifies a current-controlled current source placed between terminals t1 and t2. Vname is any independent voltage source defined elsewhere in the circuit. The current source the value of I(Vname)*gain. G -- Voltage-controlled current source: G... <t1> <t2> <NC1> <NC2> <transconductance> Specifies a voltage-controlled current source placed between terminals t1 and t2. NC1 and NC2 are the positive and negative controlling nodes, respectively. The current source has the value of (V(NC1)-V(NC2))*transconductance. - 24 - ERROR MESSAGES There are two types of error codes encountered during RESON use: 1. those detected by the RESON program, and 2. compiler run-time errors detected by Turbo Pascal. This type of error will have the format: Run-time error nnn at xxxx:yyyy All errors that don't look like that are RESON errors. RESON Errors Error # : Code Description --------------------------------------------------------- 0 : No errors encountered 1 : Matrix size is less than 1 2 : Matrix size cannot exceed CNarraysize (200) 3 : Matrix has not been opened 4 : No solution exists 5 : Source or element not found 6 : Problem not solved 7 : Index out of range 8 : User node not found 9 : Maximum number of elements or sources exceeded 10 : No elements or sources defined 11 : Illegal node connection(s) 12 : Element specifications not complete enough for attempted operation 13 : Using default parameters 14 : Illegal element value(s) 15 : Problem nodes not defined 16 : Invalid terminal specifications 17 : Element name already exists 18 : No circuit owner, or circuit owner is nil 19 : Circuit not post-processed 20 : Unknown element type 21 : Not enough memory -------------------------------------------------------- - 25 - Compiler Errors (The following was copied from Appendix A of the Turbo Pascal Programmer's Guide, v.6.0.) Run-time errors cause the program to terminate and display an error message: Run-time error nnn at xxxx:yyyy where "nnn" is the error number and "xxxx:yyyy" is the error address (segment and offset). Run-time errors are divided into four categories: DOS errors 1 through 99; I/O errors, 100 through 149; critical errors, 150 through 199; and fatal errors, 200 through 207. ----------------------------------------------------------- DOS errors 1 : Invalid function number You made a call to a non-existent DOS function. 2 : File not found Reported by Reset, Append, Rename, or Erase if the name assigned to the file variable does not specify an existing file. 3 : Path not found -- Reported by Reset, Rewrite, Append, Rename, or Erase if the name assigned to the file variable is invalid or specified a nonexistent subdirectory. -- Reported by ChDir, MkDir, or RmDir if the path is invalid or specified a nonexistent subdirectory. 4 : Too many open files Reported by Reset, Rewrite, or Append if the program has too many open files. DOS never allows more than 15 open files per process. If you get this error with less than 15 open files, it may indicate that the CONFIG.SYS file does not include a FILES=xx entry or that the entry specifies too few files. Increase the number to some suitable value, for instance, 20. - 26 - 5 : File access denied -- Reported by Reset or Append if FileMode allows writing and the name assigned to the file variable specifies a directory or a read-only file. -- Reported by Rewrite if the directory is full or if the name assigned to the file variable specifies a directory or an existing read-only file. -- Reported by Rename if the name assigned to the file variable specifies a directory or if the new name specifies an existing file. -- Reported by Erase if the name assigned to the file variable specifies a directory or a read-only file. -- Reported by MkDir if a file with the same name exists in the parent directory, if there is no room in the parent directory, or if the path specifies a device. -- Reported by RmDir if the directory isn't empty, if the path doesn't specify a directory, or if the path specifies the root directory. -- Reported by Read or BlockRead on a typed or untyped file if the file is not open for reading. -- Reported by Write or BlockWrite on a typed or untyped file if the file is not open for writing. 6 : Invalid file handle This error is reported if an invalid file handle is passed to a DOS system call. It should never occur; if it does, it is an indication that the file variable is somehow trashed. 12 : Invalid file access code Reported by Reset or Append on a typed or untyped file if the value of FileMode is invalid. 15 : Invalid drive number Reported by GetDir or ChDir if the drive number is invalid. 16 : Cannot remove current directory Reported by RmDir if the path specifies the current directory. 17 : Cannot rename across drives Reported by Rename if both names are not on the same drive. - 27 - ----------------------------------------------------------- I/O errors These errors cause termination if the particular statement was compiled in the {$|+} state. in the ($|-} state, the program continues to execute, and the error is reported by the IOResult function. 100 : Disk read error Reported by Read on a typed file if you attempt to read past the end of the file. 101 : Disk write error Reported by Close, Write, WriteIn, Flush, or Page if the disk becomes full. 102 : File not assigned Reported by Reset, ReWrite, Append, Rename, and Erase if the file variable has not been assigned a name through a call to Assign. 103 : File not open Reported by Close, Read, Write, Seek, Eof, FilePos, FileSize, Flush, BlockRead, or BlockWrite if the file is not open. 104 : File not open for input Reported by Read, ReadIn, Eof, Eoln, SeekEof, or SeekEoln on a text file if the file is not open for input. 105 : File not open for output Reported by Write and WriteIn on a text file if the file is not open for output. 106 : Invalid numeric format Reported by Read or ReadIn if a numeric value read from a text file does not conform to the proper numeric format. - 28 - ----------------------------------------------------------- Critical errors 150 : Disk is write-protected 151 : Unknown unit 152 : Drive not ready 153 : Unknown command 154 : CRC error in data 155 : Bad drive request structure length 156 : Disk seek error 157 : Unknown media type 158 : Sector not found 159 : Printer out of paper 160 : Device write fault 161 : Device read fault 162 : Hardware failure Refer to your DOS programmers' reference manual for more information about critical errors. ----------------------------------------------------------- Fatal errors These errors always immediately terminate the program. 200 : Division by zero The program attempted to divide a number by zero during a 1, mod, or div operation. 201 : Range check error This error is reported by statements compiled in the {$R+} state when one of the following situations arises: -- The index expression of an array qualifier was out of range. -- You attempted to assign an out-of-range value to a variable. -- You attempted to assign an out-of-range value as a parameter to a procedure or function. 202 : Stack overflow error This error is reported on entry to a procedure or function compiled in the {$S+} state when there is not enough stack space to allocate the subprogram's local variables. Increase the size of the stack by using the $M compiler directive. This error may also be caused by infinite recursion, or by an assembly language procedure that does not maintain the stack project. - 29 - 203 : Heap overflow error This error is reported by New or GetMem when there is not enough free space in the heap to allocate a block of the requested size. 204 : Invalid pointer operation This error is reported by Dispose or FreeMem if the pointer is nil or points to a location outside the heap, or if the free list cannot be expanded due to a full free list or to HeapPtr being too close to the bottom of the free list. 205 : Floating point overflow A floating-point operation produced a number too large for Turbo Pascal or the numeric coprocessor (if any) to handle. 206 : Floating point underflow A floating-point operation produced an underflow. This error is only reported if you are using the 8087 numeric coprocessor with a control word that unmasks underflow exceptions. By default, an underflow causes a result of zero to be returned. 207 : Invalid floating point operation -- The real value passed to Trunc or Round could not be converted to an integer within the Longint range (-2,147,483,648 to 2,147,483,647). -- The argument passed to the Sqrt function was negative.